Kanzi 3.9.10
kanzi::BrushRenderer Class Referenceabstract

An interface for specialized brush renderers, which implement brush rendering. More...

#include <kanzi/core.ui/graphics2d/brush_renderer.hpp>

Inheritance diagram for kanzi::BrushRenderer:
[legend]

Public Types

enum  RenderMode { RenderModeNone , RenderModeContent , RenderModeNoContent }
 Enum signifying currently selected render mode. More...
 

Public Member Functions

MaterialSharedPtr acquireErrorMaterial ()
 Acquires an error material for rendering.
 
void attachMaterial (MaterialSharedPtr material)
 Attaches a custom material.
 
void bind (Renderer3D &renderer)
 Binds a brush renderer for rendering.
 
void bind (Renderer3D &renderer, PropertyObject *object)
 Binds a brush renderer for rendering.
 
void draw (Renderer &renderer, const Geometry &quad, const Matrix3x3 &transform)
 Overload for drawing a brush using a given quad.
 
void draw (Renderer &renderer, const Geometry &quad, const Matrix4x4 &transform)
 Draws a brush using a given quad.
 
optional< intgetBlendModeOverride () const
 Gets the blend mode override value.
 
int getBlendModeValue () const
 Gets the last used blend mode value.
 
BrushgetBrush () const
 Gets the brush for which Kanzi created this brush renderer.
 
TextureSharedPtr getContentTexture () const
 Gets the content texture used by the brush renderer.
 
MaterialSharedPtr getMaterial () const
 Gets the currently set material for the renderer.
 
NodegetNode () const
 Gets the attached node.
 
bool getOpaquenessHint () const
 Gets the opaqueness hint value.
 
unsigned int getPropertyChangeCounter () const
 Gets the brush property change counter.
 
RenderMode getRenderMode () const
 Gets the currently selected render mode.
 
float getRenderOpacity () const
 Gets the render opacity.
 
GlRenderStategetRenderState ()
 Gets the internal render state.
 
void invalidateRenderValues ()
 Invalidates all render values.
 
bool isOpaque () const
 Indicates whether the rendered brush is opaque.
 
bool isRenderable () const
 Indicates whether a brush is in a renderable state.
 
void restoreResources ()
 Restores resources after sleep.
 
void setBlendModeOverride (optional< int > blendMode)
 Sets the blend mode override value.
 
void setContentTexture (TextureSharedPtr texture)
 Sets the content texture for the brush renderer.
 
void setOpaquenessHint (bool value)
 Sets the opaqueness hint.
 
void setRenderOpacity (float opacity)
 Sets the render opacity to use for the next attach.
 
void updateRender ()
 Prepares a brush for rendering.
 
virtual ~BrushRenderer ()=default
 Destructor.
 

Protected Member Functions

virtual bool bindOverride (Renderer3D &renderer, PropertyObject *object)
 BrushRenderer-specific bind implementation.
 
 BrushRenderer (Brush *brush, Node *node)
 Constructor.
 
virtual void drawOverride (Renderer &renderer, const Geometry &geometry, const Matrix4x4 &transform)=0
 Draws geometry using the brush.
 
virtual bool isChangeCounterSame ()
 Checks whether the property change counter matches that of the brush.
 
virtual void restoreResourcesOverride ()
 BrushRenderer-specific restore resources implementation.
 
virtual void setContentTextureOverride (TextureSharedPtr texture)
 BrushRenderer-specific update of the content texture.
 
void setRenderMode (RenderMode selection)
 Sets the render mode.
 
virtual void updateChangeCounter ()
 Updates the property change counter to match the counter value from the brush.
 
virtual void updateRenderOverride ()=0
 BrushRenderer-specific opacity override implementation.
 

Protected Attributes

Brushm_brush
 Brush attached to.
 
unsigned int m_brushPropertyChangeCounter
 Property change counter to track brush.
 
TextureSharedPtr m_contentTexture
 Content texture provided to the brush renderer from outside. For example, from Node2D.
 
GlRenderState::HandleType m_contentTextureHandle
 Render value handle.
 
bool m_isRenderable
 Indicates whether the last bind() call was successful and the brush can be rendered.
 
Nodem_node
 Node attached to.
 
RenderMode m_renderMode
 Currently used render mode (or none if not selected).
 
float m_renderOpacity
 Render opacity provided to the brush renderer from outside. For example, from Node2D.
 
GlRenderState::HandleType m_renderOpacityHandle
 Render value handle.
 
GlRenderState m_renderState
 Contained render state.
 
GlRenderValueBinding m_renderValueBinding
 Property binding handler.
 

Detailed Description

An interface for specialized brush renderers, which implement brush rendering.

You can use the BrushRenderer to render a brush manually.

To render a brush manually:

  1. Create the brush renderer by calling the implementation of the Brush::createBrushRenderer() function in the class of the brush type that you want to render.
  2. Call setContentTexture() to set the content texture for the brush renderer.

    You must do this before you call updateRender().

  3. Call updateRender() to prepare the brush for rendering.

    You must call updateRender() once after you set the content texture and before you bind the brush renderer for rendering. You do not need to call this function every time after changing the content texture, unless you change the content texture to or from nullptr.

  4. Call setRenderOpacity() to set the render opacity.

    You can do this before or after calling updateRender().

  5. (Optional) If you want to set the blend mode as determined by layouting, call setBlendModeOverride().

    This function takes precedence over the blend mode that the renderer reads from the brush.

  6. (Optional) If you want to indicate that a node can be rendered using opaque blend mode, call setOpaquenessHint().

    For example, this happens when a node is rendered as the bottom-most element in a framebuffer.

  7. Call bind() every frame before you render with the brush.
  8. To draw with the brush, call draw().

    After you call bind(), you can call draw() multiple times for different geometries and transformations.

For example:

// Create a brush.
BrushSharedPtr brush = ColorBrush::create(domain, "My Color Brush", ColorRGBA(0.4f, 0.7f, 0.8f, 1.0f));
// Create a brush renderer for the brush.
// If you render for a node, pass to this function the pointer to that node.
BrushRendererPtr brushRenderer = brush->createBrushRenderer(nullptr);
// Set the content texture for the brush renderer.
// You must do this before you call updateRender().
// You need to call updateRender() again only if you change the content texture to or from nullptr.
// The default is nullptr.
brushRenderer->setContentTexture(nullptr);
// Prepare the brush for rendering.
// You need to call updateRender() only once.
brushRenderer->updateRender();
// Set the blend mode override before you call bind().
// This is the blend mode from the layouting phase.
// To read the blend mode from the brush, use nullopt (default value).
brushRenderer->setBlendModeOverride(nullopt);
// When you want to indicate that the brush can be rendered with the opaque blend mode,
// set the opaqueness hint before you call bind().
// For example, when a brush is rendered as the first element at the back of a framebuffer,
// set the opaqueness hint to true.
// The default is false.
brushRenderer->setOpaquenessHint(false);
// Bind the brush for rendering.
// You must call bind() every frame before rendering with the brush.
brushRenderer->bind(*renderer3d);
// Draw using the brush.
// You can call draw() multiple times for different geometries and transformations after you call bind().
Matrix3x3 transform = Matrix3x3::createTranslation(50.0f, 10.0f);
brushRenderer->draw(*renderer, *geometry, transform);
Since
Kanzi 3.9.9 removed the hasRenderMode() function.

Member Enumeration Documentation

◆ RenderMode

Enum signifying currently selected render mode.

Enumerator
RenderModeNone 

No selection.

RenderModeContent 

Content specified for brush.

    \since Kanzi 3.9.1 
RenderModeNoContent 

No content specified for brush.

    \since Kanzi 3.9.1 

Constructor & Destructor Documentation

◆ ~BrushRenderer()

virtual kanzi::BrushRenderer::~BrushRenderer ( )
virtualdefault

Destructor.

◆ BrushRenderer()

kanzi::BrushRenderer::BrushRenderer ( Brush * brush,
Node * node )
explicitprotected

Constructor.

Parameters
nodeThe node to which to attach the renderer.
brushThe brush to which to attach the renderer.

Member Function Documentation

◆ updateRender()

void kanzi::BrushRenderer::updateRender ( )
inline

Prepares a brush for rendering.

Called from Node2D::updateRender(), which calls NodeVisual2D::updateRender(). Kanzi calls this function during layout.

Call this function after the brush material or attached nodes change. Unlike bind(), you do not need to call updateRender() every frame before draw().

If the render mode of a brush does not change, implementations of this function do nothing.

Since
Kanzi 3.9.1 added blendMode parameter.
Kanzi 3.9.6 removed forceOpaque parameter.
Kanzi 3.9.9 removed blendMode and translucencyHint parameters.

◆ bind() [1/2]

void kanzi::BrushRenderer::bind ( Renderer3D & renderer,
PropertyObject * object )
inline

Binds a brush renderer for rendering.

You must call this function before you call draw(). This function sets the renderable flag that you can query with isRenderable().

Parameters
rendererThe renderer to use.
objectThe object from which to fetch properties.
Since
Kanzi 3.9.7 moved here from MaterialBrushRenderer.

◆ bind() [2/2]

void kanzi::BrushRenderer::bind ( Renderer3D & renderer)
inline

Binds a brush renderer for rendering.

You must call this function before you call draw(). This function sets the renderable flag that you can query with isRenderable().

Parameters
rendererRenderer to use.

◆ draw() [1/2]

void kanzi::BrushRenderer::draw ( Renderer & renderer,
const Geometry & quad,
const Matrix4x4 & transform )

Draws a brush using a given quad.

Parameters
rendererRenderer to use.
quadQuad to draw.
transformThe transform as a 4x4 matrix to use.

◆ draw() [2/2]

void kanzi::BrushRenderer::draw ( Renderer & renderer,
const Geometry & quad,
const Matrix3x3 & transform )
inline

Overload for drawing a brush using a given quad.

Parameters
rendererRenderer to use.
quadQuad to draw.
transformThe transform as a 3x3 matrix to use.

◆ restoreResources()

void kanzi::BrushRenderer::restoreResources ( )
inline

Restores resources after sleep.

◆ getBrush()

Brush * kanzi::BrushRenderer::getBrush ( ) const
inline

Gets the brush for which Kanzi created this brush renderer.

Returns
Brush pointer.

◆ getRenderState()

GlRenderState & kanzi::BrushRenderer::getRenderState ( )
inline

Gets the internal render state.

Returns
Reference to the render state.
Since
Kanzi 3.9.7

◆ invalidateRenderValues()

void kanzi::BrushRenderer::invalidateRenderValues ( )
inline

Invalidates all render values.

Since
Kanzi 3.9.7

◆ acquireErrorMaterial()

MaterialSharedPtr kanzi::BrushRenderer::acquireErrorMaterial ( )

Acquires an error material for rendering.

Kanzi uses this function internally when the assigned material is not applicable.

Returns
Error material.
Since
Kanzi 3.9.7

◆ getPropertyChangeCounter()

unsigned int kanzi::BrushRenderer::getPropertyChangeCounter ( ) const
inline

Gets the brush property change counter.

Returns
Brush property change counter.

◆ getRenderOpacity()

float kanzi::BrushRenderer::getRenderOpacity ( ) const
inline

Gets the render opacity.

Returns
Current render opacity.

◆ setRenderOpacity()

void kanzi::BrushRenderer::setRenderOpacity ( float opacity)
inline

Sets the render opacity to use for the next attach.

Parameters
opacityNew render opacity.

◆ getContentTexture()

TextureSharedPtr kanzi::BrushRenderer::getContentTexture ( ) const
inline

Gets the content texture used by the brush renderer.

Returns
Current content texture.

◆ setContentTexture()

void kanzi::BrushRenderer::setContentTexture ( TextureSharedPtr texture)
inline

Sets the content texture for the brush renderer.

Parameters
textureThe content texture.

◆ getNode()

Node * kanzi::BrushRenderer::getNode ( ) const
inline

Gets the attached node.

Returns
Node pointer.

◆ getRenderMode()

RenderMode kanzi::BrushRenderer::getRenderMode ( ) const
inline

Gets the currently selected render mode.

Returns
Current render mode.

◆ isRenderable()

bool kanzi::BrushRenderer::isRenderable ( ) const
inline

Indicates whether a brush is in a renderable state.

To set the renderable flag, call bind().

Returns
If the brush is in a renderable state true, otherwise false.
Since
Kanzi 3.9.9

◆ getMaterial()

MaterialSharedPtr kanzi::BrushRenderer::getMaterial ( ) const

Gets the currently set material for the renderer.

Returns
Shared pointer to the material that is currently set for the brush renderer. If not set, returns nullptr.
Since
Kanzi 3.9.7 made the function non-virtual.
Kanzi 3.9.9 made the function const.

◆ getBlendModeValue()

int kanzi::BrushRenderer::getBlendModeValue ( ) const

Gets the last used blend mode value.

This function is intended for tests.

Returns
Blend mode.
Since
Kanzi 3.9.1
Kanzi 3.9.9 made the function const.

◆ setBlendModeOverride()

void kanzi::BrushRenderer::setBlendModeOverride ( optional< int > blendMode)
inline

Sets the blend mode override value.

This is the blend mode as determined by layouting. Calling this function has precedence over the blend mode read from brush or material.

Parameters
blendModeBlend mode.
Since
Kanzi 3.9.9

◆ getBlendModeOverride()

optional< int > kanzi::BrushRenderer::getBlendModeOverride ( ) const
inline

Gets the blend mode override value.

This function is intended for tests.

Returns
Blend mode override value.
Since
Kanzi 3.9.9

◆ setOpaquenessHint()

void kanzi::BrushRenderer::setOpaquenessHint ( bool value)
inline

Sets the opaqueness hint.

This hint indicates whether a node can be rendered using opaque blend mode. For example, this happens when a node is rendered as the bottom-most element in a framebuffer.

Parameters
valueOpaqueness hint value.
Since
Kanzi 3.9.9

◆ getOpaquenessHint()

bool kanzi::BrushRenderer::getOpaquenessHint ( ) const
inline

Gets the opaqueness hint value.

This function is intended for tests.

Returns
Opaqueness hint value.
Since
Kanzi 3.9.9

◆ isOpaque()

bool kanzi::BrushRenderer::isOpaque ( ) const
inline

Indicates whether the rendered brush is opaque.

Returns
If the brush is opaque, true, otherwise false.
Since
Kanzi 3.9.9

◆ attachMaterial()

void kanzi::BrushRenderer::attachMaterial ( MaterialSharedPtr material)

Attaches a custom material.

This function internally calls BrushRenderer::attachMaterial().

Parameters
materialThe material to attach.
Since
Kanzi 3.9.7 moved to the base class.

◆ drawOverride()

virtual void kanzi::BrushRenderer::drawOverride ( Renderer & renderer,
const Geometry & geometry,
const Matrix4x4 & transform )
protectedpure virtual

Draws geometry using the brush.

To be implemented by specific brush implementations.

Parameters
rendererRenderer to use.
geometryQuad to draw.
transformTransform to use.

Implemented in kanzi::ColorBrushRenderer, kanzi::ContentBrushRenderer, kanzi::MaterialBrushRenderer, and kanzi::TextureBrushRenderer.

◆ bindOverride()

virtual bool kanzi::BrushRenderer::bindOverride ( Renderer3D & renderer,
PropertyObject * object )
protectedvirtual

BrushRenderer-specific bind implementation.

Parameters
rendererRenderer to use.
objectThe object from which to fetch properties.
Returns
If the brush is renderable after binding, true, otherwise false.
Since
Kanzi 3.9.7 added object.
Kanzi 3.9.9 changed the type of the return value to bool.

Reimplemented in kanzi::ColorBrushRenderer, kanzi::ContentBrushRenderer, and kanzi::TextureBrushRenderer.

◆ updateRenderOverride()

virtual void kanzi::BrushRenderer::updateRenderOverride ( )
protectedpure virtual

BrushRenderer-specific opacity override implementation.

Since
Kanzi 3.9.1 added blendMode parameter.
Kanzi 3.9.6 removed forceOpaque parameter.
Kanzi 3.9.9 removed blendMode and translucencyHint parameters.

Implemented in kanzi::ColorBrushRenderer, kanzi::ContentBrushRenderer, kanzi::MaterialBrushRenderer, and kanzi::TextureBrushRenderer.

◆ restoreResourcesOverride()

virtual void kanzi::BrushRenderer::restoreResourcesOverride ( )
protectedvirtual

BrushRenderer-specific restore resources implementation.

◆ setContentTextureOverride()

virtual void kanzi::BrushRenderer::setContentTextureOverride ( TextureSharedPtr texture)
inlineprotectedvirtual

BrushRenderer-specific update of the content texture.

Parameters
textureNew renderer texture.
Since
Kanzi 3.9.5

◆ setRenderMode()

void kanzi::BrushRenderer::setRenderMode ( RenderMode selection)
inlineprotected

Sets the render mode.

Parameters
selectionThe render mode to set.

◆ isChangeCounterSame()

virtual bool kanzi::BrushRenderer::isChangeCounterSame ( )
protectedvirtual

Checks whether the property change counter matches that of the brush.

Returns
If the property change counter matches and no update is needed, true, otherwise false.
Since
Kanzi 3.9.7 made the function virtual.

Reimplemented in kanzi::MaterialBrushRenderer.

◆ updateChangeCounter()

virtual void kanzi::BrushRenderer::updateChangeCounter ( )
protectedvirtual

Updates the property change counter to match the counter value from the brush.

Since
Kanzi 3.9.7 made the function virtual.

Reimplemented in kanzi::MaterialBrushRenderer.

Member Data Documentation

◆ m_brush

Brush* kanzi::BrushRenderer::m_brush
protected

Brush attached to.

Since
Kanzi 3.9.1 changed protection from private to protected.

◆ m_node

Node* kanzi::BrushRenderer::m_node
protected

Node attached to.

◆ m_renderMode

RenderMode kanzi::BrushRenderer::m_renderMode
protected

Currently used render mode (or none if not selected).

◆ m_renderState

GlRenderState kanzi::BrushRenderer::m_renderState
protected

Contained render state.

Since
Kanzi 3.9.7 moved to the base class.

◆ m_renderValueBinding

GlRenderValueBinding kanzi::BrushRenderer::m_renderValueBinding
protected

Property binding handler.

Since
Kanzi 3.9.7 moved to the base class.

◆ m_renderOpacityHandle

GlRenderState::HandleType kanzi::BrushRenderer::m_renderOpacityHandle
protected

Render value handle.

Since
Kanzi 3.9.7 moved to the base class.

◆ m_contentTextureHandle

GlRenderState::HandleType kanzi::BrushRenderer::m_contentTextureHandle
protected

Render value handle.

Since
Kanzi 3.9.7 moved to the base class.

◆ m_contentTexture

TextureSharedPtr kanzi::BrushRenderer::m_contentTexture
protected

Content texture provided to the brush renderer from outside. For example, from Node2D.

◆ m_renderOpacity

float kanzi::BrushRenderer::m_renderOpacity
protected

Render opacity provided to the brush renderer from outside. For example, from Node2D.

◆ m_brushPropertyChangeCounter

unsigned int kanzi::BrushRenderer::m_brushPropertyChangeCounter
protected

Property change counter to track brush.

◆ m_isRenderable

bool kanzi::BrushRenderer::m_isRenderable
protected

Indicates whether the last bind() call was successful and the brush can be rendered.

The return value from bindOverride() is written here.

Since
Kanzi 3.9.9

The documentation for this class was generated from the following file: